Submit Application

Overview

The Submit Application API allows you to submit a complete application with company, person, and risk assessment data. This endpoint processes all the form data collected through the configuration retrieved from the Get Configuration API.

ID Field Exclusion for New Applications

When creating new applications through this endpoint, exclude the following identifier fields from your request payload:

• applicationId - Reserved for system-generated application identifiers
• company._id - Reserved for existing company record references
• person._id - Reserved for existing person record references

These identifier fields are exclusively used for referencing existing records in update operations via the Resubmit Application API.

Authentication

This endpoint requires authentication. See API Authentication for detailed requirements and how to obtain credentials.

Endpoint

PUT /api/applications/submit

Request Body

Interface Definitions

interface SubmitApplicationDTO {
   // Exclude applicationId for new application submissions
   affiliateId: string;
   applicationName: string;
   company?: UpsertCompanyDto;
   person?: UpsertPersonDto;
   riskAssessmentPayload?: SaveRiskAssessmentDTO;
}

interface UpsertPersonDto {
   // Exclude _id for new person record creation
   firstName: string;
   middleName?: string;
   lastName: string;
   fullName?: string;
   nationality?: string;
   dob?: Date;
   email?: string;
   taxNumber?: string;
   politicallyExposedPerson?: string;
   sanctionPerson?: string;
   residentOfUnitedStates?: string;
   socialProfiles?: SocialProfileDto[];
   experienceInBusiness?: string;
   relativeOrPublicPost?: string;
   telephone?: string;
   address?: AddressDto;
   identificationType?: string;
   identificationNumber?: string;
   identificationIssueDate?: string;
   identificationExpiryDate?: string;
   proofOfAddressType?: string;
   birthPlace?: string;
   sourceOfWealth?: string;
   primarySourceIncome?: string[];
   primarySourceIncomeOther?: string;
   pepDeclarationType?: string;
   pepDetail?: PepDetailDto;
   isConvictedOfFelony?: boolean;
   felonyConvictionDate?: Date;
   isInvolvedInLitigation?: boolean;
   litigationDetails?: string;
   isResidentOfUnitedStates?: boolean;
   taxResidency?: string[];
}

interface SocialProfileDto {
   socialMedia?: string;
   socialProfile?: string;
}

interface PepDetailDto {
   formerPosition?: string;
   resignationDate?: Date;
   pepPosition?: string;
   appointmentDate?: Date;
   relationship?: string;
}

interface AddressDto {
   addressLine1?: string;
   addressLine2?: string;
   postCode?: string;
   country?: string;
   city?: string;
}

interface SaveRiskAssessmentDTO {
   organisationId: string;
   riskQuestionnaireTemplateId: string;
   questions: CompanyRiskAssessmentQuestionDTO[];
}

interface CompanyRiskAssessmentQuestionDTO {
   _id: string;
   isApplicable: boolean;
   answers: string | string[];
}

Required Fields

• applicationName: Descriptive name or title for the application
• affiliateId: Unique affiliate identifier

Identifier Field Exclusion

Identifier fields (applicationId, company._id, person._id) must be excluded when creating new applications. These fields are reserved for update operations referencing existing records.

Application Type-Specific Requirements

The required fields depend on the application type determined by the configuration:

For Company Applications (type: 'company')

• company field is required
• riskAssessmentPayload is optional (only for company applications)

For Person Applications (type: 'person')

• person field is required
• riskAssessmentPayload is not applicable

Optional Fields

All other fields within the company and person objects are optional and should be included based on the configuration retrieved from the Get Configuration API and user input.

Request Example

{
   "affiliateId": "affiliate123",
   "applicationName": "John Doe Application",
   "person": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "telephone": "+1234567890",
      "nationality": "US",
      "dob": "1990-01-15T00:00:00.000Z",
      "address": {
         "addressLine1": "123 Main Street",
         "city": "New York",
         "postCode": "10001",
         "country": "US"
      },
      "identificationType": "passport",
      "identificationNumber": "P123456789",
      "sourceOfWealth": "Employment",
      "primarySourceIncome": ["employment"],
      "isResidentOfUnitedStates": true,
      "taxResidency": ["US"]
   },
   "company": {
      "name": "Example Corp",
      "tradingName": "Example Trading",
      "address": {
         "addressLine1": "456 Business Ave",
         "city": "New York",
         "postCode": "10002",
         "country": "US"
      },
      "companyType": "llc",
      "dateOfIncorporation": "2020-01-01T00:00:00.000Z"
   },
   "riskAssessmentPayload": {
      "organisationId": "60d5ecb54f3d2b001f8b4567",
      "riskQuestionnaireTemplateId": "66f5497f4434b6b086b9bb41",
      "questions": [
         {
            "_id": "66f5497f4434b6b086b9bb42",
            "isApplicable": true,
            "answers": ["66f5497f4434b6b086b9bb43"]
         },
         {
            "_id": "66f5497f4434b6b086b9bb44",
            "isApplicable": false,
            "answers": []
         }
      ]
   }
}

Response Structure

Success Response

{
   "statusCode": 200,
   "message": "Application submitted successfully",
   "data": {
      "applicationId": "60d5ecb54f3d2b001f8b4568",
      "status": "pending"
   }
}

Error Response

{
   "statusCode": 400,
   "message": "Validation failed",
   "errors": [
      {
         "field": "person.firstName",
         "message": "First name is required"
      }
   ]
}

Field Validation Requirements

• All mandatory fields must be provided in the request payload
• Email addresses must conform to valid RFC 5322 format
• Date values must be formatted according to ISO 8601 standard
• MongoDB ObjectId fields must contain valid 24-character hexadecimal strings
• Array fields must contain elements of the appropriate data type as specified in the configuration

Risk Assessment Configuration

The riskAssessmentPayload object should contain the following components:

• organisationId: Unique identifier of the organization submitting the application
• riskQuestionnaireTemplateId: Template identifier retrieved from the configuration response
• questions: Array of assessment responses structured as follows:
  • _id: Question identifier from the questionnaire template
  • isApplicable: Boolean indicating whether the question applies to this application
  • answers: Response value(s) - single string for RADIO type questions, string array for CHECKBOX type questions

Usage Guidelines

• Retrieve form configuration using the Get Configuration API prior to application submission
• Map form field values using the submitPath properties defined in the configuration response
• Submit array values for fields marked with isArray: true in the configuration
• Ensure risk assessment questions align with the template structure provided in the configuration (applicable to company applications only)

Important

Exclude all identifier fields (applicationId, company._id, person._id) when creating new applications